/*
 * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
package com.stupid.method.util;

/**
 * {@code StringJoiner} is used to construct a sequence of characters separated
 * by a delimiter and optionally starting with a supplied prefix and ending with
 * a supplied suffix.
 * <p>
 * Prior to adding something to the {@code StringJoiner}, its
 * {@code sj.toString()} method will, by default, return {@code prefix + suffix}
 * . However, if the {@code setEmptyValue} method is called, the
 * {@code emptyValue} supplied will be returned instead. This can be used, for
 * example, when creating a string using set notation to indicate an empty set,
 * i.e. <code>"{}"</code>, where the {@code prefix} is <code>"{"</code>, the
 * {@code suffix} is <code>"}"</code> and nothing has been added to the
 * {@code StringJoiner}.
 * 
 * @apiNote <p>
 *          The String {@code "[George:Sally:Fred]"} may be constructed as
 *          follows:
 * 
 *          <pre>
 * {
 * 	&#064;code
 * 	StringJoiner sj = new StringJoiner(&quot;:&quot;, &quot;[&quot;, &quot;]&quot;);
 * 	sj.add(&quot;George&quot;).add(&quot;Sally&quot;).add(&quot;Fred&quot;);
 * 	String desiredString = sj.toString();
 * }
 * </pre>
 *          <p>
 *          A {@code StringJoiner} may be employed to create formatted output
 *          from a {@link java.util.stream.Stream} using
 *          {@link java.util.stream.Collectors#joining(CharSequence)}. For
 *          example:
 * 
 *          <pre>
 * {@code
 * List<Integer> numbers = Arrays.asList(1, 2, 3, 4);
 * String commaSeparatedNumbers = numbers.stream()
 *     .map(i -> i.toString())
 *     .collect(Collectors.joining(", "));
 * }
 * </pre>
 * 
 * @see java.util.stream.Collectors#joining(CharSequence)
 * @see java.util.stream.Collectors#joining(CharSequence, CharSequence,
 *      CharSequence)
 * @since 1.8
 */
public final class StringJoiner {
	private final String prefix;
	private final String delimiter;
	private final String suffix;

	/*
	 * StringBuilder value -- at any time, the characters constructed from the
	 * prefix, the added element separated by the delimiter, but without the
	 * suffix, so that we can more easily add elements without having to jigger
	 * the suffix each time.
	 */
	private StringBuilder value;

	/*
	 * By default, the string consisting of prefix+suffix, returned by
	 * toString(), or properties of value, when no elements have yet been added,
	 * i.e. when it is empty. This may be overridden by the user to be some
	 * other value including the empty String.
	 */
	private String emptyValue;

	/**
	 * Constructs a {@code StringJoiner} with no characters in it, with no
	 * {@code prefix} or {@code suffix}, and a copy of the supplied
	 * {@code delimiter}. If no characters are added to the {@code StringJoiner}
	 * and methods accessing the value of it are invoked, it will not return a
	 * {@code prefix} or {@code suffix} (or properties thereof) in the result,
	 * unless {@code setEmptyValue} has first been called.
	 * 
	 * @param delimiter
	 *            the sequence of characters to be used between each element
	 *            added to the {@code StringJoiner} value
	 * @throws NullPointerException
	 *             if {@code delimiter} is {@code null}
	 */
	public StringJoiner(CharSequence delimiter) {
		this(delimiter, "", "");
	}

	/**
	 * Constructs a {@code StringJoiner} with no characters in it using copies
	 * of the supplied {@code prefix}, {@code delimiter} and {@code suffix}. If
	 * no characters are added to the {@code StringJoiner} and methods accessing
	 * the string value of it are invoked, it will return the
	 * {@code prefix + suffix} (or properties thereof) in the result, unless
	 * {@code setEmptyValue} has first been called.
	 * 
	 * @param delimiter
	 *            the sequence of characters to be used between each element
	 *            added to the {@code StringJoiner}
	 * @param prefix
	 *            the sequence of characters to be used at the beginning
	 * @param suffix
	 *            the sequence of characters to be used at the end
	 * @throws NullPointerException
	 *             if {@code prefix}, {@code delimiter}, or {@code suffix} is
	 *             {@code null}
	 */
	public StringJoiner(CharSequence delimiter, CharSequence prefix,
			CharSequence suffix) {
		ObjectUtils.requireNonNull(prefix, "The prefix must not be null");
		ObjectUtils.requireNonNull(delimiter, "The delimiter must not be null");
		ObjectUtils.requireNonNull(suffix, "The suffix must not be null");
		// make defensive copies of arguments
		this.prefix = prefix.toString();
		this.delimiter = delimiter.toString();
		this.suffix = suffix.toString();
		this.emptyValue = this.prefix + this.suffix;
	}

	/**
	 * Sets the sequence of characters to be used when determining the string
	 * representation of this {@code StringJoiner} and no elements have been
	 * added yet, that is, when it is empty. A copy of the {@code emptyValue}
	 * parameter is made for this purpose. Note that once an add method has been
	 * called, the {@code StringJoiner} is no longer considered empty, even if
	 * the element(s) added correspond to the empty {@code String}.
	 * 
	 * @param emptyValue
	 *            the characters to return as the value of an empty
	 *            {@code StringJoiner}
	 * @return this {@code StringJoiner} itself so the calls may be chained
	 * @throws NullPointerException
	 *             when the {@code emptyValue} parameter is {@code null}
	 */
	public StringJoiner setEmptyValue(CharSequence emptyValue) {
		this.emptyValue = ObjectUtils.requireNonNull(emptyValue,
				"The empty value must not be null").toString();
		return this;
	}

	/**
	 * Returns the current value, consisting of the {@code prefix}, the values
	 * added so far separated by the {@code delimiter}, and the {@code suffix},
	 * unless no elements have been added in which case, the
	 * {@code prefix + suffix} or the {@code emptyValue} characters are returned
	 * 
	 * @return the string representation of this {@code StringJoiner}
	 */
	@Override
	public String toString() {
		if (value == null) {
			return emptyValue;
		} else {
			if (suffix.equals("")) {
				return value.toString();
			} else {
				int initialLength = value.length();
				String result = value.append(suffix).toString();
				// reset value to pre-append initialLength
				value.setLength(initialLength);
				return result;
			}
		}
	}

	/**
	 * Adds a copy of the given {@code CharSequence} value as the next element
	 * of the {@code StringJoiner} value. If {@code newElement} is {@code null},
	 * then {@code "null"} is added.
	 * 
	 * @param newElement
	 *            The element to add
	 * @return a reference to this {@code StringJoiner}
	 */
	public StringJoiner add(CharSequence newElement) {
		prepareBuilder().append(newElement);
		return this;
	}

	/**
	 * Adds the contents of the given {@code StringJoiner} without prefix and
	 * suffix as the next element if it is non-empty. If the given
	 * {@code StringJoiner} is empty, the call has no effect.
	 * 
	 * <p>
	 * A {@code StringJoiner} is empty if {@link #add(CharSequence) add()} has
	 * never been called, and if {@code merge()} has never been called with a
	 * non-empty {@code StringJoiner} argument.
	 * 
	 * <p>
	 * If the other {@code StringJoiner} is using a different delimiter, then
	 * elements from the other {@code StringJoiner} are concatenated with that
	 * delimiter and the result is appended to this {@code StringJoiner} as a
	 * single element.
	 * 
	 * @param other
	 *            The {@code StringJoiner} whose contents should be merged into
	 *            this one
	 * @throws NullPointerException
	 *             if the other {@code StringJoiner} is null
	 * @return This {@code StringJoiner}
	 */
	public StringJoiner merge(StringJoiner other) {
		ObjectUtils.requireNonNull(other);
		if (other.value != null) {
			final int length = other.value.length();
			// lock the length so that we can seize the data to be appended
			// before initiate copying to avoid interference, especially when
			// merge 'this'
			StringBuilder builder = prepareBuilder();
			builder.append(other.value, other.prefix.length(), length);
		}
		return this;
	}

	private StringBuilder prepareBuilder() {
		if (value != null) {
			value.append(delimiter);
		} else {
			value = new StringBuilder().append(prefix);
		}
		return value;
	}

	/**
	 * Returns the length of the {@code String} representation of this
	 * {@code StringJoiner}. Note that if no add methods have been called, then
	 * the length of the {@code String} representation (either
	 * {@code prefix + suffix} or {@code emptyValue}) will be returned. The
	 * value should be equivalent to {@code toString().length()}.
	 * 
	 * @return the length of the current value of {@code StringJoiner}
	 */
	public int length() {
		// Remember that we never actually append the suffix unless we return
		// the full (present) value or some sub-string or length of it, so that
		// we can add on more if we need to.
		return (value != null ? value.length() + suffix.length() : emptyValue
				.length());
	}
}
